dxp-ux
g4p-73q/queryUsageConsumption-TMF677 for CWC (Mobile)
This retrieves the usages for CWC BusinessIDs and Panama.
- PA - Prepaid: Ericsson
- PA, CWC - Postpaid: Liberate
- CWC - Prepaid: Limeware
URL
https://[localhost]:[port]/dxp-ux/v1/{businessId}/queryUsageConsumptionURL PARAMS
| name | type | description | required |
|---|---|---|---|
| businessId | string | 2 letter ISO 3166 country code (JM,VC,LC,GD,AG,TC,KY,AI,KN,MS,VG,DM) identifying the business unit. | Y |
Header
| name | value | description | required |
|---|---|---|---|
| client_id | string | The client_id identifying the channel. | Y |
| client_secret | string | Password associated with the client_id. | Y |
| X-Correlation-ID | string | An identifier for the current call chain that can be used to tie together log entries on multiple layers (e.g. client, server, mainframe). This identifier must be designed to be unique across all applications. Note - Mule default behavior creates a sample x-correlation-id field if value is not passed from client, API will use this value in case value is not passed in API request | Y |
QueryParameter
| name | value | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| usageConsumption.logicalResource.id | string | Need to provide valid MSISDN or SubscriptionId value | Y (CWC, PA) |
| searchCriteria.service.@type | string | This indicates the service line of business. possible values are "PREPAID" and "POSTPAID" | Y (CWC, PA) |
| relatedParty.id | string | unique identifier of the account. Mandatory when businessIDs contains CWC or PA (liberate) markets and searchCriteria.service.@type is POSTPAID | cond.Y (CWC, PA) |
| bucket.bucketRelationship.relationshipType | string | This is used to fetch account level usages. If this query Param is not passed then only ServiceLevel Usages will be retrieved Allowed Values are "BillingAccount" | N(CWC, PA) |
Data Model - Response Data Model
| name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| id | string | unique identifier | Y(PA, CWC) |
| queryUsageConsumptionDate | datetime | Date when the query was submitted | Y(PA, CWC) |
| searchCriteria | object | An usage consumption enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). It could be calculated for a device identified by a public key (msisdn number for a mobile device for example or PSTN or VOIP number for a fix device), for a subscribed offer or option or for an user. | Y(PA, CWC) |
| searchCriteria.service[] | array | Service reference, for when Service is used by other entities | Y(PA, CWC) |
| searchCriteria.service[].id | string | unique identifier | Y(PA, CWC) |
| searchCriteria.service[].@type | string | type of service <br(example: PREPAID, POSTPAID) | Y(PA, CWC) |
| relatedParty[] | array | Reference and role of the related parties for which the usage consumption is requested | N(PA, CWC) |
| relatedParty[].id | string | unique identifier | N(PA, CWC) |
| relatedParty[].@type | string | type of the relatedParty Here it is billingAccount | N(PA, CWC) |
| usageConsumption[] | array | Report with current counters and balances | Y(PA, CWC) |
| usageConsumption[].id | string | unique identifier | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[] | array | Bucket(s) included in the offer or option subscribed. | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].id | string | Unique Identifier within the server for the bucket | Y(PA) N(CWC) |
| usageConsumption[].bucketRefOrValue[].isShared | boolean | True if the bucket is shared between several devices or users | Y(PA) N(CWC) |
| usageConsumption[].bucketRefOrValue[].name | string | Friendly name to identify the bucket | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].description | string | Text describing the contents of the balance managed by | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].remainingValueName | string | Remaining amount in a formatted string for the bucket given in the balance unit (for example 1.9 Gb). This formatted string could be used for display needs for example | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].status | string | status for the bucket. active, expired, suspended | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].usageType | string | defines the type of the underlying Balance eg data,voice, any currency eg EUR, USD etc | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[] | array | The consumption counters (called ConsumptionSummary in the SID model) detail for example the different kind of consumption done on the bucket. Note: bucketCounter is only retrieved for POSTPAID. | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].counterType | string | Type of the consumption counter. We can give for example a counter of the used value for a bucket (counterType=used for example) or the value of the consumption done out of the bucket(s) (counterType=outOfBucket for example) | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].valueName | string | Value of the counter in a formatted string used for display needs for example | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].consumptionPeriod | object | A period of time, either as a deadline (endDateTime only) a startDateTime only, or both | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].consumptionPeriod.endDateTime | datetime | End of the time period, using IETC-RFC-3339 format | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].value | object | An amount in a given unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].value.amount | number | Numeric value in a given unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].value.units | string | Unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].bucketCounter[].@type | string | type of the bucketCounter | N(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].remainingValue | object | An amount in a given unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].remainingValue.amount | number | Numeric value in a given unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].remainingValue.units | string | Unit | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].validFor | object | A period of time, either as a deadline (endDateTime only) a startDateTime only, or both | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].validFor.endDateTime | datetime | End of the time period, using IETC-RFC-3339 format | Y(PA, CWC) |
| usageConsumption[].bucketRefOrValue[].validFor.startDateTime | datetime | Start of the time period, using IETC-RFC-3339 format | N(PA, CWC) |
| usageConsumption[].logicalResource | object | reference to the LogicalResource eg MSISDN | Y(PA, CWC) |
| usageConsumption[].logicalResource.id | string | unique identifier | Y(PA, CWC) |
| usageConsumption[].logicalResource.@type | string | type of logicalResource. Here it is MSISDN | Y(PA, CWC) |
| usageConsumption[].@type | string | When sub-classing, this defines the sub-class Extensible name | Y(PA, CWC) |
bucketCounter subResource - dataModel
| CounterType | description | required(mandatory-Y, optional-N, Not applicable- N/A) | examples |
|---|---|---|---|
| used | Type of the consumption counter. We can give for example a counter of the used value for a bucket (counterType=used for example) | Y(PA, CWC) | { "counterType": "used", "valueName": "Minutes", "consumptionPeriod": { "endDateTime": "2021-02-28T00:00:00.000-05:00" }, "value": { "amount": 0.00, "units": "MINS" }, "@type": "UnitsUsed" } |
| allocated | Type of the consumption counter. We can give for example a counter of the used value for a bucket (counterType=allocated for example) | Y(PA, CWC) | { "counterType": "allocated", "valueName": "Minutes", "consumptionPeriod": { "endDateTime": "2021-02-28T00:00:00.000-05:00" }, "value": { "amount": 100.00, "units": "MINS" }, "@type": "UnitsAllocated" } |
| carried | Type of the consumption counter. We can give for example a counter of the used value for a bucket (counterType=carried for example) | Y(PA, CWC) | { "counterType": "carried", "valueName": "Minutes", "consumptionPeriod": { "endDateTime": "2021-02-28T00:00:00.000-05:00" }, "value": { "amount": 0.00, "units": "MINS" }, "@type": "UnitsCarriedOver" } |
Key considerations
Please find the responses in following URL DXP UX - QueryUsageConsumption API
Key considerations for CWC (flow markets)
- This is applicable for Mobile POSTPAID and Mobile PREPAID for liberate Customers only.
- For CWC Liberate postpaid, data will be retrieved from Liberate and Limeware for BUs(JM,VC,LC,GD,AG,TC,KY,AI,KN,MS,VG,DM). Limeware response gives SAPC balances, whereas liberate provides all balances/usage. Input parameters are service/subscriber number and account number. The response which has usageConsumption[].id are the usage retrieved from Liberate, remaining would be the SAPC balances retrieved from Limeware.
- To retrieve data from Liberate. Then service number need to be provided without country code and BU code for all BUs excluding JM. For Jamaica, the serviceNumber should be sent including BU code (i.e 876 for JM).
- Current implementation fetches the service level usage for the provided service number and also account level usage for the provided account number. In the response structure, the objects which have "logicalResource" object in usageConsumption arrayObject can be considered as service level usage, the objects which doesn't have "logicalResource" object and @type under usageConsumption arrayObject with name "AccountUsageConsumption" will be considered as account level usages.
- for CWC prepaid, data will be retrieved from Limeware for BUs(JM,VC,LC,GD,AG,TC,KY,AI,KN,MS,VG,DM). Limeware response gives all the prepaid balances/usage. Input parameters are service/subscriber number.
key considerations for PA:
1. Prepaid Data Retrieval:
- Data will be retrieved from Ericsson with serviceNumber as input.
2. Postpaid Data Retrieval:
- Data will be retrieved from liberate with accountNumber and ServiceNumber as input.
3. Service Number Format:
- The service number should be provided without country code and BU code (e.g., 66717668).
4. Account and Service Level Usages - POSTPAID:
- To retrieve account level and service level usages, queryParameter "bucket.bucketRelationship.relationshipType" should be sent and value must be provided as "BillingAccount".
- To retrieve the service level usages, queryParameter usageConsumption.logicalResource.id and relatedParty.id must be sent as input.
- In the response structure, When @type under usageConsumptionObject is "AccountUsageConsumption", It can be considered as account level usage. remaining usageConsumptionObjects will be service level
usages.
5. Possible Usage Types:
- POSTPAID: Duration (calls), Volume (data), Number of Calls (SMS)
- PREPAID: monetary, voice, sms, data, others.
6. BucketCounters:
- Retrieved for postpaid accounts/services from Liberate along with remaining amounts. Possible values for counters includes used, allocated, carried.
- For prepaid, only the remaining amount is retrieved from Ericsson
7. For all the dateTime fields
- Any datetime before 1908-04-22 will show offset -05:18
- Any datetime on or after 1908-04-22 will show offset -05:00